habiticafandomcom-20200222-history
Guidance for Blacksmiths
Blacksmiths are vital to the success of Habitica. Your contributions are needed and appreciated! There are several ways to contribute coding expertise to the website and mobile apps. A great first step in getting acquainted with what needs to be done is reading all of this page and the pages it links to, then joining the Aspiring Blacksmiths (Habitica Coders) guild to ask any questions you might have. Be sure to also read Setting up Habitica Locally for important information about getting started and then Using Your Local Install to Modify Habitica's Website and API to learn processes for creating code changes. Ways to Help Website Below are tips for finding items to work on, depending on how you would like to contribute. In all cases, check the notes for the current status of the item and whether anyone else is actively working on it (e.g., if a pull request is linked, someone has already submitted a fix). If someone else has already recently commented to say they are working on a Github issue or Trello card, please leave the work for them. However, if it has been many days since their last comment, they might no longer have time to contribute to Habitica, and then it could be appropriate for you to ask if you can take it over. Before you start work, it's important that you post a comment on the GitHub issue or Trello card to express your interest in working on it, and then wait for a response from an admin. This is because some issues and feature requests will not always be suitable for actioning (for example during a code refactoring period). This is true even of the issues labeled with the GitHub Labels listed below. Depending on the issue or feature, you might like to describe your suggested approach so that admins can comment on whether it's suitable. * I want to start small: Check out the Github issue queue and search for items labeled good first issue for issues where you can ask to contribute. * I want to help where I'm most needed: Search for Github issues labeled , , and and ask to contribute before starting. Solving a bug labeled will allow you to earn the Critical Hammer of Bug-Crushing. As we work to polish the recent frontend overhaul, pull requests addressing issues labeled will receive expedited review and contributor credit. * I want to create unit tests & Karma tests!: Welcome, bug-slayer! Please refer to the "Creating and Running Automated Tests" section in "Using Your Local Install to Modify Habitica's Website and API" for further information. * I want to build things!: Make way for the new hero! Watch the issue queue because staff will sometimes create issues for new features that have been approved for implementation. If you can't find something there that interests you, you can look through the Trello feature queue but it is vital that you ask first to find out if a feature request you select is approved by the staff. Some feature suggestions are not suitable for implementation and a pull request that implements them would not be accepted. The website's repository uses other labels in addition to the ones listed above. You can read about them in GitHub Labels, but the ones listed above will be of most use in finding useful issues to work on. Mobile App for iOS * The iOS "Habitica" app has its own code base in its own GitHub repository at github.com/HabitRPG/habitica-ios. It is open source and contributions are welcome. * If you want to contribute to the iOS app, the Issue list contains a list of already requested features and known bugs. Feel free to look through them to find things you would like to work on. In order to prevent duplicate work, a comment should be left on the issue you intend to work on. If you would like to work on a feature that does not yet have an existing issue, please create one first, so that implementation details can be discussed. Mobile App for Android *The Android "Habitica" app has its own code base in its own GitHub repository at github.com/HabitRPG/habitica-android. It is open source and contributions are welcome. * If you want to contribute to the Android app, the Issue list contains a list of already requested features and known bugs. Feel free to look through them to find things you would like to work on. In order to prevent duplicate work, a comment should be left on the issue you intend to work on. If you would like to work on a feature that does not yet have an existing issue, please create one first, so that implementation details can be discussed. BountySource Some issues will have BountySource bounties on them, posted by staff or users. If your fix for such an issue is accepted, you will be able to claim the money as payment. In all other ways, these issues are treated identically to issues without bounties, so follow all the normal guidelines for them (e.g., asking first if it's okay for you to work on the issue). Website Technology Stack The technologies Habitica uses for its website are listed below. You don't need to be familiar with all of them, or even most of them, to be able to contribute! Some links to high-quality learning material are also included. Many of these technologies (namely, the ones with '.js' or 'JS' in the name or URL) are based on the programming language JavaScript, which you can learn here. Server Client Testing Reverse-Engineered Requirements Documents In June 2019, students from the University of Brasília analyzed Habitica for a project. Their aim was to reverse-engineer Habitica's website to develop requirements artifacts. This section displays two of the Rich Pictures that they developed. A Rich Picture is a way to explore a situation and express it through diagrams, showing its flow. Although these Pictures are not official Habitica documents, they might assist a new code contributor to develop an understanding of the site and aid in development of features and bug fixes. Click each image to see a larger version. The images were sourced from their project wiki at https://requisitos-habitica.netlify.com. Working with a Local Installation Blacksmiths should create a local running instance of Habitica, for testing and development. The process to create a local instance can be difficult, so we've collected steps for each operating system at Setting up Habitica Locally. The process of using your local installation to make changes and create pull requests is described in Using Your Local Install to Modify Habitica's Website and API. MongoDB To learn how to use MongoDB, we recommend reading the official MongoDB documentation or another reliable online resource, but here are a few examples of basic commands to help new developers gain a quick understanding of using MongoDB. You can run these statements in the MongoDB command line interface (CLI) or with a GUI tool such as Robo 3T IDE's IntelliShell. In the commands below, the $ sign indicates a Unix, Windows or Git Shell prompt and the > sign indicates a Mongo CLI shell prompt. Type only the text that appears after $ or > into your command line. To access the Mongo shell and then select your local install's Habitica database: $ mongo > show dbs > use habitrpg Alternatively, directly start the shell with the database selected: $ mongo habitrpg View the "collections" in the database ("users", "groups", etc): > show collections View the full "document" for one user in the "users" collection (the user's User ID is 12345678-b5b9-4bb4-8b82-123456789abc): > db.users.find({_id: '12345678-b5b9-4bb4-8b82-123456789abc'})0 View only the preferences object from the user's document: > db.users.find({_id: '12345678-b5b9-4bb4-8b82-123456789abc'})0.preferences Change a value for the user using the update method with $set: > db.users.update({_id: '12345678-b5b9-4bb4-8b82-123456789abc'}, {$set: {'profile.name':'New Display Name'}}) Using Your Local Install to Modify Habitica's Website and API has advanced examples for specific purposes that are likely to be useful to you when testing your code changes. Translatable Strings (locales files) Translatable strings appear in files in the website/common/locales/en directory. Each string consists of a key and a piece of text, for example: 'clearAll': 'clear all items', Do not edit files in other directories under website/common/locales because all translations are managed in Weblate. Always test your string additions and edits by viewing them in your local install. Never merely assume that even simple string additions will work as expected. Adding Translatable Strings To add a new translatable string write it in a Vue or JavaScript file using the t function. For example: env.t("newKey") i18n.t('newKey') Find existing strings in the file you are modifying for examples. Then, in the website/common/locales/en directory, edit the appropriate json files, adding the new string as follows: 'newKey': 'String Title', If there are already strings in the json file about the same topic, then it's preferred that you add your new string in the same place as the existing ones, to keep similar strings together. If there are no similar strings, add yours at the end of the file. Add a comma to the existing string that used to be the last string in the file. Do not add a comma to the end of your final string. Modifying Translatable Strings Existing strings can be changed whenever necessary. Do not change the keys unless there's a good reason to do so. For example: if you needed to change the string 'clear all items' to 'delete all items', you would not also change its key 'clearAll' to 'deleteAll', since the meaning of the original key is still accurate. The reason the keys are usually not changed is because they can be referenced in more than one place in Habitica's code and so all of those pieces of code would need to be updated; this is undesirable unless there's a good reason for it. In addition, when a key is changed the translators need to redo the translations without having the original translation visible for comparison. Note that when there is a reason to change the keys, you still should not modify the locales directories for languages other than English. Images For information about creating new images for Habitica, see Guidance for Artisans. When a new image has been prepared and approved by the staff, an issue will be created to request it be added to Habitica. A Blacksmith will then need to add it to the repository. Most images will need to be copied into suitable subdirectories under website/client/assets/ After adding new images or new versions of existing images, run npm run sprites to recompile the image spritesheets. Sometimes, this command will result in a new spritesheet being created, in which case use git add to add the new files. You will find them under website/client/assets/images/sprites/ and website/client/assets/css/sprites/ Other Useful Commands Here are various helpful commands. Search code You'll often want to search all files containing some keyword or string, to determine what files need to be edited when adding/editing some feature. Use the grep command (search online for information about grep on your operating system) or the git grep command (git documentation will teach you about how to use it). Preference Settings Habitica has preference settings for the users to customize the website's behavior. New settings may be added if necessary. Please do not add settings only a small proportion of users are likely to use, or settings for trivial customizations. Instead choose a behavior the majority of users are likely to enjoy. Too many preferences makes the settings screen look cluttered and increases the appearance of complexity. If you're uncertain about whether a preference setting is desirable, you can discuss it in the relevant GitHub issue or pull request. When a new user preference setting is necessary, it can be added to file(s) under website/server/models/user/. Generally, the database will then pick them up the new setting automatically and add it to user accounts as necessary. If it is ever necessary for the database to be modified manually, admins can do that. "Information for Developers" Sections on General Wiki Pages At the bottom of some wiki pages, are sections called Information for Developers. These contain useful tips for Blacksmiths related to the content on that page. The information is hidden behind a spoiler-style show/hide toggle button so it doesn't clutter the page for non-technical users. The sections use the and templates to ensure correct formatting and wording for the buttons and other text. To see how that is done, open any page with an Information for Developers section in the source editor. To see a list of all pages with this section, use the "What links here" tool for the 'Start' template. To see all Information for Developers sections unhidden by default: * Create a Wikia account if you don't already have one. * Edit your personal Wikia css file, located at: http://habitica.fandom.com/wiki/User:YOUR_USERNAME_HERE/wikia.css * Insert these lines into CSS file: /* Force all "Information for Developers" sections to always be visible */ .habitrpg-InfoForDevs { display:block !important; } .habitrpg-InfoForDevs-hideIfDev { display:none; } You can see an example at User:LadyAlys/wikia.css Contributor Tier Process You're in luck! Blacksmiths do not need to do anything special, like complete a Contributor Tier request (as Scribes are requested to do), in order to earn Contributor Tiers. Contributor Tiers for Blacksmiths will be granted by the admins as they review and accept Blacksmith submissions. Admins will track Blacksmith contributions for credit toward future Contributor Tiers. The first one or two Contributor Tiers from Blacksmithing are fairly easy to get, and you might find that a single pull request being completed is enough for each of them. The higher tiers require progressively more work, and several successful pull requests might be needed. Admins will record each pull request when it is completed, and will award a tier when enough contributions have been made. Generally, when a PR is merged, an admin will write in both the PR and Hall of Heroes something like "I've given you Tier x" or "Noted toward your next contributor tier." If they write something like the latter, it means that PR alone was not enough for a tier by itself, or not enough to increase your tier to the next level if you already had other partial credit towards it. If an admin does not make any comment on your PR about credit towards contributor Tiers, please post to the PR to ask about it! Admins sometimes do forget and they always appreciate a gentle reminder because giving contributors credit for their work is important! See Also * Setting up Habitica Locally * Using Your Local Install to Modify Habitica's Website and API * Application Programming Interface * GitHub ** GitHub Labels ** BountySource ** Critical Hammer of Bug-Crushing * Wiki Pages that Include Information for Developers fr:Guide de la forge ru:Руководство для кузнецов Category:Contributing Category:ToBeReviewed